
package org.apache.mina.common;

import java.io.IOException;

/**
 * Handles all I/O events fired by MINA.
 * 
 * 处理所有由MINA触发的IO事件
 */
public interface IoHandler {
    /**
     * Invoked from an I/O processor thread when a new connection has been
     * created. Because this method is supposed to be called from the same
     * thread that handles I/O of multiple sessions, please implement this
     * method to perform tasks that consumes minimal amount of time such as
     * socket parameter and user-defined session attribute initialization.
     * 
     * 当一个新的连接被创建时，该方法会被IO处理线程所调用。
     * 
     * 因为该方法支持被处理多个session的IO线程调用，所以应该实现该方法去执行耗时小的任务，比如socket参数初始化、
     * 用户自定义session属性的初始化。
     */
    void sessionCreated(IoSession session) throws Exception;

    /**
     * Invoked when a connection has been opened. This method is invoked after
     * {@link #sessionCreated(IoSession)}. The biggest difference from
     * {@link #sessionCreated(IoSession)} is that it's invoked from other thread
     * than an I/O processor thread once thread modesl is configured properly.
     * 
     * 当打开一个连接时，就调用该方法。在调用sessionCreated(IoSession)之后才调用此方法。
     * 
     * 与sessionCreated(IoSession)最大的不同点在于：如果正确配置线程模型，它是被别的线程而不是IO处理线程所调用，
     */
    void sessionOpened(IoSession session) throws Exception;

    /**
     * Invoked when a connection is closed.
     * 
     * 当关闭一个连接时，将会调用此方法。
     */
    void sessionClosed(IoSession session) throws Exception;

    /**
     * Invoked with the related {@link IdleStatus} when a connection becomes
     * idle. This method is not invoked if the transport type is UDP; it's a
     * known bug, and will be fixed in 2.0.
     * 
     * 当一个连接变成空闲时，将会与相关的IdleStatus一起被调用。
     * 
     * 如果是UDP协议，该方法将不会被调用，这是一个BUG，将在2.0中修复它。
     */
    void sessionIdle(IoSession session, IdleStatus status) throws Exception;

    /**
     * Invoked when any exception is thrown by user {@link IoHandler}
     * implementation or by MINA. If <code>cause</code> is instanceof
     * {@link IOException}, MINA will close the connection automatically.
     * 
     * 当用户的IoHandler实现类或MINA抛出异常时，将被调用。
     * 
     * 如果cause是IOException，MINA将会自动关闭此连接。
     */
    void exceptionCaught(IoSession session, Throwable cause) throws Exception;

    /**
     * Invoked when a message is received. 当收到一个消息时，将会调用此方法。
     */
    void messageReceived(IoSession session, Object message) throws Exception;

    /**
     * Invoked when a message written by {@link IoSession#write(Object)} is sent
     * out.
     * 
     * 当IoSession.write(Object)向外发送一条消息的时候，将会调用此方法。
     */
    void messageSent(IoSession session, Object message) throws Exception;
}